home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / share / pyshared / couchdb / client.py < prev    next >
Text File  |  2009-08-19  |  37KB  |  1,097 lines
  1. # -*- coding: utf-8 -*-
  2. #
  3. # Copyright (C) 2007-2009 Christopher Lenz
  4. # All rights reserved.
  5. #
  6. # This software is licensed as described in the file COPYING, which
  7. # you should have received as part of this distribution.
  8.  
  9. """Python client API for CouchDB.
  10.  
  11. >>> server = Server('http://localhost:5984/')
  12. >>> db = server.create('python-tests')
  13. >>> doc_id = db.create({'type': 'Person', 'name': 'John Doe'})
  14. >>> doc = db[doc_id]
  15. >>> doc['type']
  16. 'Person'
  17. >>> doc['name']
  18. 'John Doe'
  19. >>> del db[doc.id]
  20. >>> doc.id in db
  21. False
  22.  
  23. >>> del server['python-tests']
  24. """
  25.  
  26. import httplib2
  27. import mimetypes
  28. from urllib import quote, urlencode
  29. from types import FunctionType
  30. from inspect import getsource
  31. from textwrap import dedent
  32. import re
  33. import socket
  34. import sys
  35.  
  36. from couchdb import json
  37.  
  38. __all__ = ['PreconditionFailed', 'ResourceNotFound', 'ResourceConflict',
  39.            'ServerError', 'Server', 'Database', 'Document', 'ViewResults',
  40.            'Row']
  41. __docformat__ = 'restructuredtext en'
  42.  
  43.  
  44. DEFAULT_BASE_URI = 'http://localhost:5984/'
  45.  
  46.  
  47. class PreconditionFailed(Exception):
  48.     """Exception raised when a 412 HTTP error is received in response to a
  49.     request.
  50.     """
  51.  
  52.  
  53. class ResourceNotFound(Exception):
  54.     """Exception raised when a 404 HTTP error is received in response to a
  55.     request.
  56.     """
  57.  
  58.  
  59. class ResourceConflict(Exception):
  60.     """Exception raised when a 409 HTTP error is received in response to a
  61.     request.
  62.     """
  63.  
  64.  
  65. class ServerError(Exception):
  66.     """Exception raised when an unexpected HTTP error is received in response
  67.     to a request.
  68.     """
  69.  
  70.  
  71. class Server(object):
  72.     """Representation of a CouchDB server.
  73.  
  74.     >>> server = Server('http://localhost:5984/')
  75.  
  76.     This class behaves like a dictionary of databases. For example, to get a
  77.     list of database names on the server, you can simply iterate over the
  78.     server object.
  79.  
  80.     New databases can be created using the `create` method:
  81.  
  82.     >>> db = server.create('python-tests')
  83.     >>> db
  84.     <Database 'python-tests'>
  85.  
  86.     You can access existing databases using item access, specifying the database
  87.     name as the key:
  88.  
  89.     >>> db = server['python-tests']
  90.     >>> db.name
  91.     'python-tests'
  92.  
  93.     Databases can be deleted using a ``del`` statement:
  94.  
  95.     >>> del server['python-tests']
  96.     """
  97.  
  98.     def __init__(self, uri=DEFAULT_BASE_URI, cache=None, timeout=None):
  99.         """Initialize the server object.
  100.  
  101.         :param uri: the URI of the server (for example
  102.                     ``http://localhost:5984/``)
  103.         :param cache: either a cache directory path (as a string) or an object
  104.                       compatible with the ``httplib2.FileCache`` interface. If
  105.                       `None` (the default), no caching is performed.
  106.         :param timeout: socket timeout in number of seconds, or `None` for no
  107.                         timeout
  108.         """
  109.         if sys.version_info < (2, 6):
  110.             http = httplib2.Http(cache=cache)
  111.         else:
  112.             http = httplib2.Http(cache=cache, timeout=timeout)
  113.         http.force_exception_to_status_code = False
  114.         self.resource = Resource(http, uri)
  115.  
  116.     def __contains__(self, name):
  117.         """Return whether the server contains a database with the specified
  118.         name.
  119.  
  120.         :param name: the database name
  121.         :return: `True` if a database with the name exists, `False` otherwise
  122.         """
  123.         try:
  124.             self.resource.head(validate_dbname(name))
  125.             return True
  126.         except ResourceNotFound:
  127.             return False
  128.  
  129.     def __iter__(self):
  130.         """Iterate over the names of all databases."""
  131.         resp, data = self.resource.get('_all_dbs')
  132.         return iter(data)
  133.  
  134.     def __len__(self):
  135.         """Return the number of databases."""
  136.         resp, data = self.resource.get('_all_dbs')
  137.         return len(data)
  138.  
  139.     def __nonzero__(self):
  140.         """Return whether the server is available."""
  141.         try:
  142.             self.resource.head()
  143.             return True
  144.         except:
  145.             return False
  146.  
  147.     def __repr__(self):
  148.         return '<%s %r>' % (type(self).__name__, self.resource.uri)
  149.  
  150.     def __delitem__(self, name):
  151.         """Remove the database with the specified name.
  152.  
  153.         :param name: the name of the database
  154.         :raise ResourceNotFound: if no database with that name exists
  155.         """
  156.         self.resource.delete(validate_dbname(name))
  157.  
  158.     def __getitem__(self, name):
  159.         """Return a `Database` object representing the database with the
  160.         specified name.
  161.  
  162.         :param name: the name of the database
  163.         :return: a `Database` object representing the database
  164.         :rtype: `Database`
  165.         :raise ResourceNotFound: if no database with that name exists
  166.         """
  167.         db = Database(uri(self.resource.uri, name), validate_dbname(name),
  168.                       http=self.resource.http)
  169.         db.resource.head() # actually make a request to the database
  170.         return db
  171.  
  172.     @property
  173.     def config(self):
  174.         """The configuration of the CouchDB server.
  175.  
  176.         The configuration is represented as a nested dictionary of sections and
  177.         options from the configuration files of the server, or the default
  178.         values for options that are not explicitly configured.
  179.  
  180.         :type: `dict`
  181.         """
  182.         resp, data = self.resource.get('_config')
  183.         return data
  184.  
  185.     @property
  186.     def version(self):
  187.         """The version string of the CouchDB server.
  188.  
  189.         Note that this results in a request being made, and can also be used
  190.         to check for the availability of the server.
  191.  
  192.         :type: `unicode`"""
  193.         resp, data = self.resource.get()
  194.         return data['version']
  195.  
  196.     def create(self, name):
  197.         """Create a new database with the given name.
  198.  
  199.         :param name: the name of the database
  200.         :return: a `Database` object representing the created database
  201.         :rtype: `Database`
  202.         :raise PreconditionFailed: if a database with that name already exists
  203.         """
  204.         self.resource.put(validate_dbname(name))
  205.         return self[name]
  206.  
  207.     def delete(self, name):
  208.         """Delete the database with the specified name.
  209.  
  210.         :param name: the name of the database
  211.         :raise ResourceNotFound: if a database with that name does not exist
  212.         :since: 0.6
  213.         """
  214.         del self[name]
  215.  
  216.  
  217. class Database(object):
  218.     """Representation of a database on a CouchDB server.
  219.  
  220.     >>> server = Server('http://localhost:5984/')
  221.     >>> db = server.create('python-tests')
  222.  
  223.     New documents can be added to the database using the `create()` method:
  224.  
  225.     >>> doc_id = db.create({'type': 'Person', 'name': 'John Doe'})
  226.  
  227.     This class provides a dictionary-like interface to databases: documents are
  228.     retrieved by their ID using item access
  229.  
  230.     >>> doc = db[doc_id]
  231.     >>> doc                 #doctest: +ELLIPSIS
  232.     <Document '...'@... {...}>
  233.  
  234.     Documents are represented as instances of the `Row` class, which is
  235.     basically just a normal dictionary with the additional attributes ``id`` and
  236.     ``rev``:
  237.  
  238.     >>> doc.id, doc.rev     #doctest: +ELLIPSIS
  239.     ('...', ...)
  240.     >>> doc['type']
  241.     'Person'
  242.     >>> doc['name']
  243.     'John Doe'
  244.  
  245.     To update an existing document, you use item access, too:
  246.  
  247.     >>> doc['name'] = 'Mary Jane'
  248.     >>> db[doc.id] = doc
  249.  
  250.     The `create()` method creates a document with a random ID generated by
  251.     CouchDB (which is not recommended). If you want to explicitly specify the
  252.     ID, you'd use item access just as with updating:
  253.  
  254.     >>> db['JohnDoe'] = {'type': 'person', 'name': 'John Doe'}
  255.  
  256.     >>> 'JohnDoe' in db
  257.     True
  258.     >>> len(db)
  259.     2
  260.  
  261.     >>> del server['python-tests']
  262.     """
  263.  
  264.     def __init__(self, uri, name=None, http=None):
  265.         self.resource = Resource(http, uri)
  266.         self._name = name
  267.  
  268.     def __repr__(self):
  269.         return '<%s %r>' % (type(self).__name__, self.name)
  270.  
  271.     def __contains__(self, id):
  272.         """Return whether the database contains a document with the specified
  273.         ID.
  274.  
  275.         :param id: the document ID
  276.         :return: `True` if a document with the ID exists, `False` otherwise
  277.         """
  278.         try:
  279.             self.resource.head(id)
  280.             return True
  281.         except ResourceNotFound:
  282.             return False
  283.  
  284.     def __iter__(self):
  285.         """Return the IDs of all documents in the database."""
  286.         return iter([item.id for item in self.view('_all_docs')])
  287.  
  288.     def __len__(self):
  289.         """Return the number of documents in the database."""
  290.         resp, data = self.resource.get()
  291.         return data['doc_count']
  292.  
  293.     def __nonzero__(self):
  294.         """Return whether the database is available."""
  295.         try:
  296.             self.resource.head()
  297.             return True
  298.         except:
  299.             return False
  300.  
  301.     def __delitem__(self, id):
  302.         """Remove the document with the specified ID from the database.
  303.  
  304.         :param id: the document ID
  305.         """
  306.         resp, data = self.resource.head(id)
  307.         self.resource.delete(id, rev=resp['etag'].strip('"'))
  308.  
  309.     def __getitem__(self, id):
  310.         """Return the document with the specified ID.
  311.  
  312.         :param id: the document ID
  313.         :return: a `Row` object representing the requested document
  314.         :rtype: `Document`
  315.         """
  316.         resp, data = self.resource.get(id)
  317.         return Document(data)
  318.  
  319.     def __setitem__(self, id, content):
  320.         """Create or update a document with the specified ID.
  321.  
  322.         :param id: the document ID
  323.         :param content: the document content; either a plain dictionary for
  324.                         new documents, or a `Row` object for existing
  325.                         documents
  326.         """
  327.         resp, data = self.resource.put(id, content=content)
  328.         content.update({'_id': data['id'], '_rev': data['rev']})
  329.  
  330.     @property
  331.     def name(self):
  332.         """The name of the database.
  333.  
  334.         Note that this may require a request to the server unless the name has
  335.         already been cached by the `info()` method.
  336.  
  337.         :type: basestring
  338.         """
  339.         if self._name is None:
  340.             self.info()
  341.         return self._name
  342.  
  343.     def create(self, data):
  344.         """Create a new document in the database with a random ID that is
  345.         generated by the server.
  346.  
  347.         Note that it is generally better to avoid the `create()` method and
  348.         instead generate document IDs on the client side. This is due to the
  349.         fact that the underlying HTTP ``POST`` method is not idempotent, and
  350.         an automatic retry due to a problem somewhere on the networking stack
  351.         may cause multiple documents being created in the database.
  352.  
  353.         To avoid such problems you can generate a UUID on the client side.
  354.         Python (since version 2.5) comes with a ``uuid`` module that can be
  355.         used for this::
  356.  
  357.             from uuid import uuid4
  358.             doc_id = uuid4().hex
  359.             db[doc_id] = {'type': 'person', 'name': 'John Doe'}
  360.  
  361.         :param data: the data to store in the document
  362.         :return: the ID of the created document
  363.         :rtype: `unicode`
  364.         """
  365.         resp, data = self.resource.post(content=data)
  366.         return data['id']
  367.  
  368.     def compact(self):
  369.         """Compact the database.
  370.  
  371.         This will try to prune all revisions from the database.
  372.  
  373.         :return: a boolean to indicate whether the compaction was initiated
  374.                  successfully
  375.         :rtype: `bool`
  376.         """
  377.         resp, data = self.resource.post('_compact')
  378.         return data['ok']
  379.  
  380.     def copy(self, src, dest):
  381.         """Copy the given document to create a new document.
  382.  
  383.         :param src: the ID of the document to copy, or a dictionary or
  384.                     `Document` object representing the source document.
  385.         :param dest: either the destination document ID as string, or a
  386.                      dictionary or `Document` instance of the document that
  387.                      should be overwritten.
  388.         :return: the new revision of the destination document
  389.         :rtype: `str`
  390.         :since: 0.6
  391.         """
  392.         if not isinstance(src, basestring):
  393.             if not isinstance(src, dict):
  394.                 if hasattr(src, 'items'):
  395.                     src = src.items()
  396.                 else:
  397.                     raise TypeError('expected dict or string, got %s' %
  398.                                     type(src))
  399.             src = src['_id']
  400.  
  401.         if not isinstance(dest, basestring):
  402.             if not isinstance(dest, dict):
  403.                 if hasattr(dest, 'items'):
  404.                     dest = dest.items()
  405.                 else:
  406.                     raise TypeError('expected dict or string, got %s' %
  407.                                     type(dest))
  408.             if '_rev' in dest:
  409.                 dest = '%s?%s' % (unicode_quote(dest['_id']),
  410.                                   unicode_urlencode({'rev': dest['_rev']}))
  411.             else:
  412.                 dest = unicode_quote(dest['_id'])
  413.  
  414.         resp, data = self.resource._request('COPY', src,
  415.                                             headers={'Destination': dest})
  416.         return data['rev']
  417.  
  418.     def delete(self, doc):
  419.         """Delete the given document from the database.
  420.  
  421.         Use this method in preference over ``__del__`` to ensure you're
  422.         deleting the revision that you had previously retrieved. In the case
  423.         the document has been updated since it was retrieved, this method will
  424.         raise a `ResourceConflict` exception.
  425.  
  426.         >>> server = Server('http://localhost:5984/')
  427.         >>> db = server.create('python-tests')
  428.  
  429.         >>> doc = dict(type='Person', name='John Doe')
  430.         >>> db['johndoe'] = doc
  431.         >>> doc2 = db['johndoe']
  432.         >>> doc2['age'] = 42
  433.         >>> db['johndoe'] = doc2
  434.         >>> db.delete(doc)
  435.         Traceback (most recent call last):
  436.           ...
  437.         ResourceConflict: ('conflict', 'Document update conflict.')
  438.  
  439.         >>> del server['python-tests']
  440.  
  441.         :param doc: a dictionary or `Document` object holding the document data
  442.         :raise ResourceConflict: if the document was updated in the database
  443.         :since: 0.4.1
  444.         """
  445.         self.resource.delete(doc['_id'], rev=doc['_rev'])
  446.  
  447.     def get(self, id, default=None, **options):
  448.         """Return the document with the specified ID.
  449.  
  450.         :param id: the document ID
  451.         :param default: the default value to return when the document is not
  452.                         found
  453.         :return: a `Row` object representing the requested document, or `None`
  454.                  if no document with the ID was found
  455.         :rtype: `Document`
  456.         """
  457.         try:
  458.             resp, data = self.resource.get(id, **options)
  459.         except ResourceNotFound:
  460.             return default
  461.         else:
  462.             return Document(data)
  463.  
  464.     def info(self):
  465.         """Return information about the database as a dictionary.
  466.  
  467.         The returned dictionary exactly corresponds to the JSON response to
  468.         a ``GET`` request on the database URI.
  469.  
  470.         :return: a dictionary of database properties
  471.         :rtype: ``dict``
  472.         :since: 0.4
  473.         """
  474.         resp, data = self.resource.get()
  475.         self._name = data['db_name']
  476.         return data
  477.  
  478.     def delete_attachment(self, doc, filename):
  479.         """Delete the specified attachment.
  480.  
  481.         Note that the provided `doc` is required to have a ``_rev`` field.
  482.         Thus, if the `doc` is based on a view row, the view row would need to
  483.         include the ``_rev`` field.
  484.  
  485.         :param doc: the dictionary or `Document` object representing the
  486.                     document that the attachment belongs to
  487.         :param filename: the name of the attachment file
  488.         :since: 0.4.1
  489.         """
  490.         resp, data = self.resource(doc['_id']).delete(filename, rev=doc['_rev'])
  491.         doc['_rev'] = data['rev']
  492.  
  493.     def get_attachment(self, id_or_doc, filename, default=None):
  494.         """Return an attachment from the specified doc id and filename.
  495.  
  496.         :param id_or_doc: either a document ID or a dictionary or `Document`
  497.                           object representing the document that the attachment
  498.                           belongs to
  499.         :param filename: the name of the attachment file
  500.         :param default: default value to return when the document or attachment
  501.                         is not found
  502.         :return: the content of the attachment as a string, or the value of the
  503.                  `default` argument if the attachment is not found
  504.         :since: 0.4.1
  505.         """
  506.         if isinstance(id_or_doc, basestring):
  507.             id = id_or_doc
  508.         else:
  509.             id = id_or_doc['_id']
  510.         try:
  511.             resp, data = self.resource(id).get(filename)
  512.             return data
  513.         except ResourceNotFound:
  514.             return default
  515.  
  516.     def put_attachment(self, doc, content, filename=None, content_type=None):
  517.         """Create or replace an attachment.
  518.  
  519.         Note that the provided `doc` is required to have a ``_rev`` field. Thus,
  520.         if the `doc` is based on a view row, the view row would need to include
  521.         the ``_rev`` field.
  522.  
  523.         :param doc: the dictionary or `Document` object representing the
  524.                     document that the attachment should be added to
  525.         :param content: the content to upload, either a file-like object or
  526.                         a string
  527.         :param filename: the name of the attachment file; if omitted, this
  528.                          function tries to get the filename from the file-like
  529.                          object passed as the `content` argument value
  530.         :param content_type: content type of the attachment; if omitted, the
  531.                              MIME type is guessed based on the file name
  532.                              extension
  533.         :since: 0.4.1
  534.         """
  535.         if hasattr(content, 'read'):
  536.             content = content.read()
  537.         if filename is None:
  538.             if hasattr(content, 'name'):
  539.                 filename = content.name
  540.             else:
  541.                 raise ValueError('no filename specified for attachment')
  542.         if content_type is None:
  543.             content_type = ';'.join(filter(None, mimetypes.guess_type(filename)))
  544.  
  545.         resp, data = self.resource(doc['_id']).put(filename, content=content,
  546.                                                    headers={
  547.             'Content-Type': content_type
  548.         }, rev=doc['_rev'])
  549.         doc['_rev'] = data['rev']
  550.  
  551.     def query(self, map_fun, reduce_fun=None, language='javascript',
  552.               wrapper=None, **options):
  553.         """Execute an ad-hoc query (a "temp view") against the database.
  554.  
  555.         >>> server = Server('http://localhost:5984/')
  556.         >>> db = server.create('python-tests')
  557.         >>> db['johndoe'] = dict(type='Person', name='John Doe')
  558.         >>> db['maryjane'] = dict(type='Person', name='Mary Jane')
  559.         >>> db['gotham'] = dict(type='City', name='Gotham City')
  560.         >>> map_fun = '''function(doc) {
  561.         ...     if (doc.type == 'Person')
  562.         ...         emit(doc.name, null);
  563.         ... }'''
  564.         >>> for row in db.query(map_fun):
  565.         ...     print row.key
  566.         John Doe
  567.         Mary Jane
  568.  
  569.         >>> for row in db.query(map_fun, descending=True):
  570.         ...     print row.key
  571.         Mary Jane
  572.         John Doe
  573.  
  574.         >>> for row in db.query(map_fun, key='John Doe'):
  575.         ...     print row.key
  576.         John Doe
  577.  
  578.         >>> del server['python-tests']
  579.  
  580.         :param map_fun: the code of the map function
  581.         :param reduce_fun: the code of the reduce function (optional)
  582.         :param language: the language of the functions, to determine which view
  583.                          server to use
  584.         :param wrapper: an optional callable that should be used to wrap the
  585.                         result rows
  586.         :param options: optional query string parameters
  587.         :return: the view reults
  588.         :rtype: `ViewResults`
  589.         """
  590.         return TemporaryView(uri(self.resource.uri, '_temp_view'), map_fun,
  591.                              reduce_fun, language=language, wrapper=wrapper,
  592.                              http=self.resource.http)(**options)
  593.  
  594.     def update(self, documents, **options):
  595.         """Perform a bulk update or insertion of the given documents using a
  596.         single HTTP request.
  597.  
  598.         >>> server = Server('http://localhost:5984/')
  599.         >>> db = server.create('python-tests')
  600.         >>> for doc in db.update([
  601.         ...     Document(type='Person', name='John Doe'),
  602.         ...     Document(type='Person', name='Mary Jane'),
  603.         ...     Document(type='City', name='Gotham City')
  604.         ... ]):
  605.         ...     print repr(doc) #doctest: +ELLIPSIS
  606.         (True, '...', '...')
  607.         (True, '...', '...')
  608.         (True, '...', '...')
  609.  
  610.         >>> del server['python-tests']
  611.  
  612.         The return value of this method is a list containing a tuple for every
  613.         element in the `documents` sequence. Each tuple is of the form
  614.         ``(success, docid, rev_or_exc)``, where ``success`` is a boolean
  615.         indicating whether the update succeeded, ``docid`` is the ID of the
  616.         document, and ``rev_or_exc`` is either the new document revision, or
  617.         an exception instance (e.g. `ResourceConflict`) if the update failed.
  618.  
  619.         If an object in the documents list is not a dictionary, this method
  620.         looks for an ``items()`` method that can be used to convert the object
  621.         to a dictionary. Effectively this means you can also use this method
  622.         with `schema.Document` objects.
  623.  
  624.         :param documents: a sequence of dictionaries or `Document` objects, or
  625.                           objects providing a ``items()`` method that can be
  626.                           used to convert them to a dictionary
  627.         :return: an iterable over the resulting documents
  628.         :rtype: ``list``
  629.  
  630.         :since: version 0.2
  631.         """
  632.         docs = []
  633.         for doc in documents:
  634.             if isinstance(doc, dict):
  635.                 docs.append(doc)
  636.             elif hasattr(doc, 'items'):
  637.                 docs.append(dict(doc.items()))
  638.             else:
  639.                 raise TypeError('expected dict, got %s' % type(doc))
  640.  
  641.         content = options
  642.         content.update(docs=docs)
  643.         resp, data = self.resource.post('_bulk_docs', content=content)
  644.  
  645.         results = []
  646.         for idx, result in enumerate(data):
  647.             if 'error' in result:
  648.                 if result['error'] == 'conflict':
  649.                     exc_type = ResourceConflict
  650.                 else:
  651.                     # XXX: Any other error types mappable to exceptions here?
  652.                     exc_type = ServerError
  653.                 results.append((False, result['id'],
  654.                                 exc_type(result['reason'])))
  655.             else:
  656.                 doc = documents[idx]
  657.                 if isinstance(doc, dict): # XXX: Is this a good idea??
  658.                     doc.update({'_id': result['id'], '_rev': result['rev']})
  659.                 results.append((True, result['id'], result['rev']))
  660.  
  661.         return results
  662.  
  663.     def view(self, name, wrapper=None, **options):
  664.         """Execute a predefined view.
  665.  
  666.         >>> server = Server('http://localhost:5984/')
  667.         >>> db = server.create('python-tests')
  668.         >>> db['gotham'] = dict(type='City', name='Gotham City')
  669.  
  670.         >>> for row in db.view('_all_docs'):
  671.         ...     print row.id
  672.         gotham
  673.  
  674.         >>> del server['python-tests']
  675.  
  676.         :param name: the name of the view; for custom views, use the format
  677.                      ``design_docid/viewname``, that is, the document ID of the
  678.                      design document and the name of the view, separated by a
  679.                      slash
  680.         :param wrapper: an optional callable that should be used to wrap the
  681.                         result rows
  682.         :param options: optional query string parameters
  683.         :return: the view results
  684.         :rtype: `ViewResults`
  685.         """
  686.         if not name.startswith('_'):
  687.             design, name = name.split('/', 1)
  688.             name = '/'.join(['_design', design, '_view', name])
  689.         return PermanentView(uri(self.resource.uri, *name.split('/')), name,
  690.                              wrapper=wrapper,
  691.                              http=self.resource.http)(**options)
  692.  
  693.  
  694. class Document(dict):
  695.     """Representation of a document in the database.
  696.  
  697.     This is basically just a dictionary with the two additional properties
  698.     `id` and `rev`, which contain the document ID and revision, respectively.
  699.     """
  700.  
  701.     def __repr__(self):
  702.         return '<%s %r@%r %r>' % (type(self).__name__, self.id, self.rev,
  703.                                   dict([(k,v) for k,v in self.items()
  704.                                         if k not in ('_id', '_rev')]))
  705.  
  706.     @property
  707.     def id(self):
  708.         """The document ID.
  709.  
  710.         :type: basestring
  711.         """
  712.         return self['_id']
  713.  
  714.     @property
  715.     def rev(self):
  716.         """The document revision.
  717.  
  718.         :type: basestring
  719.         """
  720.         return self['_rev']
  721.  
  722.  
  723. class View(object):
  724.     """Abstract representation of a view or query."""
  725.  
  726.     def __init__(self, uri, wrapper=None, http=None):
  727.         self.resource = Resource(http, uri)
  728.         self.wrapper = wrapper
  729.  
  730.     def __call__(self, **options):
  731.         return ViewResults(self, options)
  732.  
  733.     def __iter__(self):
  734.         return self()
  735.  
  736.     def _encode_options(self, options):
  737.         retval = {}
  738.         for name, value in options.items():
  739.             if name in ('key', 'startkey', 'endkey') \
  740.                     or not isinstance(value, basestring):
  741.                 value = json.encode(value)
  742.             retval[name] = value
  743.         return retval
  744.  
  745.     def _exec(self, options):
  746.         raise NotImplementedError
  747.  
  748.  
  749. class PermanentView(View):
  750.     """Representation of a permanent view on the server."""
  751.  
  752.     def __init__(self, uri, name, wrapper=None, http=None):
  753.         View.__init__(self, uri, wrapper=wrapper, http=http)
  754.         self.name = name
  755.  
  756.     def __repr__(self):
  757.         return '<%s %r>' % (type(self).__name__, self.name)
  758.  
  759.     def _exec(self, options):
  760.         if 'keys' in options:
  761.             options = options.copy()
  762.             keys = {'keys': options.pop('keys')}
  763.             resp, data = self.resource.post(content=keys,
  764.                                             **self._encode_options(options))
  765.         else:
  766.             resp, data = self.resource.get(**self._encode_options(options))
  767.         return data
  768.  
  769.  
  770. class TemporaryView(View):
  771.     """Representation of a temporary view."""
  772.  
  773.     def __init__(self, uri, map_fun, reduce_fun=None,
  774.                  language='javascript', wrapper=None, http=None):
  775.         View.__init__(self, uri, wrapper=wrapper, http=http)
  776.         if isinstance(map_fun, FunctionType):
  777.             map_fun = getsource(map_fun).rstrip('\n\r')
  778.         self.map_fun = dedent(map_fun.lstrip('\n\r'))
  779.         if isinstance(reduce_fun, FunctionType):
  780.             reduce_fun = getsource(reduce_fun).rstrip('\n\r')
  781.         if reduce_fun:
  782.             reduce_fun = dedent(reduce_fun.lstrip('\n\r'))
  783.         self.reduce_fun = reduce_fun
  784.         self.language = language
  785.  
  786.     def __repr__(self):
  787.         return '<%s %r %r>' % (type(self).__name__, self.map_fun,
  788.                                self.reduce_fun)
  789.  
  790.     def _exec(self, options):
  791.         body = {'map': self.map_fun, 'language': self.language}
  792.         if self.reduce_fun:
  793.             body['reduce'] = self.reduce_fun
  794.         if 'keys' in options:
  795.             options = options.copy()
  796.             body['keys'] = options.pop('keys')
  797.         content = json.encode(body).encode('utf-8')
  798.         resp, data = self.resource.post(content=content, headers={
  799.             'Content-Type': 'application/json'
  800.         }, **self._encode_options(options))
  801.         return data
  802.  
  803.  
  804. class ViewResults(object):
  805.     """Representation of a parameterized view (either permanent or temporary)
  806.     and the results it produces.
  807.  
  808.     This class allows the specification of ``key``, ``startkey``, and
  809.     ``endkey`` options using Python slice notation.
  810.  
  811.     >>> server = Server('http://localhost:5984/')
  812.     >>> db = server.create('python-tests')
  813.     >>> db['johndoe'] = dict(type='Person', name='John Doe')
  814.     >>> db['maryjane'] = dict(type='Person', name='Mary Jane')
  815.     >>> db['gotham'] = dict(type='City', name='Gotham City')
  816.     >>> map_fun = '''function(doc) {
  817.     ...     emit([doc.type, doc.name], doc.name);
  818.     ... }'''
  819.     >>> results = db.query(map_fun)
  820.  
  821.     At this point, the view has not actually been accessed yet. It is accessed
  822.     as soon as it is iterated over, its length is requested, or one of its
  823.     `rows`, `total_rows`, or `offset` properties are accessed:
  824.  
  825.     >>> len(results)
  826.     3
  827.  
  828.     You can use slices to apply ``startkey`` and/or ``endkey`` options to the
  829.     view:
  830.  
  831.     >>> people = results[['Person']:['Person','ZZZZ']]
  832.     >>> for person in people:
  833.     ...     print person.value
  834.     John Doe
  835.     Mary Jane
  836.     >>> people.total_rows, people.offset
  837.     (3, 1)
  838.  
  839.     Use plain indexed notation (without a slice) to apply the ``key`` option.
  840.     Note that as CouchDB makes no claim that keys are unique in a view, this
  841.     can still return multiple rows:
  842.  
  843.     >>> list(results[['City', 'Gotham City']])
  844.     [<Row id='gotham', key=['City', 'Gotham City'], value='Gotham City'>]
  845.  
  846.     >>> del server['python-tests']
  847.     """
  848.  
  849.     def __init__(self, view, options):
  850.         self.view = view
  851.         self.options = options
  852.         self._rows = self._total_rows = self._offset = None
  853.  
  854.     def __repr__(self):
  855.         return '<%s %r %r>' % (type(self).__name__, self.view, self.options)
  856.  
  857.     def __getitem__(self, key):
  858.         options = self.options.copy()
  859.         if type(key) is slice:
  860.             if key.start is not None:
  861.                 options['startkey'] = key.start
  862.             if key.stop is not None:
  863.                 options['endkey'] = key.stop
  864.             return ViewResults(self.view, options)
  865.         else:
  866.             options['key'] = key
  867.             return ViewResults(self.view, options)
  868.  
  869.     def __iter__(self):
  870.         wrapper = self.view.wrapper
  871.         for row in self.rows:
  872.             if wrapper is not None:
  873.                 yield wrapper(row)
  874.             else:
  875.                 yield row
  876.  
  877.     def __len__(self):
  878.         return len(self.rows)
  879.  
  880.     def _fetch(self):
  881.         data = self.view._exec(self.options)
  882.         self._rows = [Row(row) for row in data['rows']]
  883.         self._total_rows = data.get('total_rows')
  884.         self._offset = data.get('offset', 0)
  885.  
  886.     @property
  887.     def rows(self):
  888.         """The list of rows returned by the view.
  889.  
  890.         :type: `list`
  891.         """
  892.         if self._rows is None:
  893.             self._fetch()
  894.         return self._rows
  895.  
  896.     @property
  897.     def total_rows(self):
  898.         """The total number of rows in this view.
  899.  
  900.         This value is `None` for reduce views.
  901.  
  902.         :type: `int` or ``NoneType`` for reduce views
  903.         """
  904.         if self._rows is None:
  905.             self._fetch()
  906.         return self._total_rows
  907.  
  908.     @property
  909.     def offset(self):
  910.         """The offset of the results from the first row in the view.
  911.  
  912.         This value is 0 for reduce views.
  913.  
  914.         :type: `int`
  915.         """
  916.         if self._rows is None:
  917.             self._fetch()
  918.         return self._offset
  919.  
  920.  
  921. class Row(dict):
  922.     """Representation of a row as returned by database views."""
  923.  
  924.     def __repr__(self):
  925.         if self.id is None:
  926.             return '<%s key=%r, value=%r>' % (type(self).__name__, self.key,
  927.                                               self.value)
  928.         return '<%s id=%r, key=%r, value=%r>' % (type(self).__name__, self.id,
  929.                                                  self.key, self.value)
  930.  
  931.     @property
  932.     def id(self):
  933.         """The associated Document ID if it exists. Returns `None` when it
  934.         doesn't (reduce results).
  935.         """
  936.         return self.get('id')
  937.  
  938.     @property
  939.     def key(self):
  940.         """The associated key."""
  941.         return self['key']
  942.  
  943.     @property
  944.     def value(self):
  945.         """The associated value."""
  946.         return self['value']
  947.  
  948.     @property
  949.     def doc(self):
  950.         """The associated document for the row. This is only present when the
  951.         view was accessed with ``include_docs=True`` as a query parameter,
  952.         otherwise this property will be `None`.
  953.         """
  954.         doc = self.get('doc')
  955.         if doc:
  956.             return Document(doc)
  957.  
  958.  
  959. # Internals
  960.  
  961.  
  962. class Resource(object):
  963.  
  964.     def __init__(self, http, uri):
  965.         if http is None:
  966.             http = httplib2.Http()
  967.             http.force_exception_to_status_code = False
  968.         self.http = http
  969.         self.uri = uri
  970.  
  971.     def __call__(self, path):
  972.         return type(self)(self.http, uri(self.uri, path))
  973.  
  974.     def delete(self, path=None, headers=None, **params):
  975.         return self._request('DELETE', path, headers=headers, **params)
  976.  
  977.     def get(self, path=None, headers=None, **params):
  978.         return self._request('GET', path, headers=headers, **params)
  979.  
  980.     def head(self, path=None, headers=None, **params):
  981.         return self._request('HEAD', path, headers=headers, **params)
  982.  
  983.     def post(self, path=None, content=None, headers=None, **params):
  984.         return self._request('POST', path, content=content, headers=headers,
  985.                              **params)
  986.  
  987.     def put(self, path=None, content=None, headers=None, **params):
  988.         return self._request('PUT', path, content=content, headers=headers,
  989.                              **params)
  990.  
  991.     def _request(self, method, path=None, content=None, headers=None,
  992.                  **params):
  993.         from couchdb import __version__
  994.         headers = headers or {}
  995.         headers.setdefault('Accept', 'application/json')
  996.         headers.setdefault('User-Agent', 'couchdb-python %s' % __version__)
  997.         body = None
  998.         if content is not None:
  999.             if not isinstance(content, basestring):
  1000.                 body = json.encode(content).encode('utf-8')
  1001.                 headers.setdefault('Content-Type', 'application/json')
  1002.             else:
  1003.                 body = content
  1004.             headers.setdefault('Content-Length', str(len(body)))
  1005.  
  1006.         def _make_request(retry=1):
  1007.             try:
  1008.                 return self.http.request(uri(self.uri, path, **params), method,
  1009.                                              body=body, headers=headers)
  1010.             except socket.error, e:
  1011.                 if retry > 0 and e.args[0] == 54: # reset by peer
  1012.                     return _make_request(retry - 1)
  1013.                 raise
  1014.         resp, data = _make_request()
  1015.  
  1016.         status_code = int(resp.status)
  1017.         if data and resp.get('content-type') == 'application/json':
  1018.             try:
  1019.                 data = json.decode(data)
  1020.             except ValueError:
  1021.                 pass
  1022.  
  1023.         if status_code >= 400:
  1024.             if type(data) is dict:
  1025.                 error = (data.get('error'), data.get('reason'))
  1026.             else:
  1027.                 error = data
  1028.             if status_code == 404:
  1029.                 raise ResourceNotFound(error)
  1030.             elif status_code == 409:
  1031.                 raise ResourceConflict(error)
  1032.             elif status_code == 412:
  1033.                 raise PreconditionFailed(error)
  1034.             else:
  1035.                 raise ServerError((status_code, error))
  1036.  
  1037.         return resp, data
  1038.  
  1039.  
  1040. def uri(base, *path, **query):
  1041.     """Assemble a uri based on a base, any number of path segments, and query
  1042.     string parameters.
  1043.  
  1044.     >>> uri('http://example.org/', '/_all_dbs')
  1045.     'http://example.org/_all_dbs'
  1046.     """
  1047.     if base and base.endswith('/'):
  1048.         base = base[:-1]
  1049.     retval = [base]
  1050.  
  1051.     # build the path
  1052.     path = '/'.join([''] +
  1053.                     [unicode_quote(s.strip('/')) for s in path
  1054.                      if s is not None])
  1055.     if path:
  1056.         retval.append(path)
  1057.  
  1058.     # build the query string
  1059.     params = []
  1060.     for name, value in query.items():
  1061.         if type(value) in (list, tuple):
  1062.             params.extend([(name, i) for i in value if i is not None])
  1063.         elif value is not None:
  1064.             if value is True:
  1065.                 value = 'true'
  1066.             elif value is False:
  1067.                 value = 'false'
  1068.             params.append((name, value))
  1069.     if params:
  1070.         retval.extend(['?', unicode_urlencode(params)])
  1071.  
  1072.     return ''.join(retval)
  1073.  
  1074.  
  1075. def unicode_quote(string, safe=''):
  1076.     if isinstance(string, unicode):
  1077.         string = string.encode('utf-8')
  1078.     return quote(string, safe)
  1079.  
  1080.  
  1081. def unicode_urlencode(data):
  1082.     if isinstance(data, dict):
  1083.         data = data.items()
  1084.     params = []
  1085.     for name, value in data:
  1086.         if isinstance(value, unicode):
  1087.             value = value.encode('utf-8')
  1088.         params.append((name, value))
  1089.     return urlencode(params)
  1090.  
  1091.  
  1092. VALID_DB_NAME = re.compile(r'^[a-z][a-z0-9_$()+-/]*$')
  1093. def validate_dbname(name):
  1094.     if not VALID_DB_NAME.match(name):
  1095.         raise ValueError('Invalid database name')
  1096.     return name
  1097.